# Creare una dilazione
## Introduzione
Per attivare una dilazione o un pagamento è necessario prima inviare una richiesta di dilazione, quindi reindirizzare l'utente al gateway di pagamento con l'identificativo della dilazione ricevuto, passando un URL di ritorno. Il gateway reindirizzerà all'URL inviato per gestire il ritorno del pagamento.
## Inviare una richiesta di dilazione

L'endpoint chiede l'avviamento della dilazione e ritorna l'identificativo per il reindirizzamento.
### Richiesta Http
```bash
POST https://api.jatapay.it/scrivi_dilazione
```
### Parametri
| Parametro | Richiesto | Tipo |  Descrizione |
| -------------- | -------------- | -------------- |-------------- |
| importo   | Sì |  int  | L'importo totale della dilazione espresso in centesimi di Euro   |
|  rate  | Sì | int   |  Il numero di rate della dilazione  |
|  callback_url  | Sì | string   |  Un URL valido per il ritorno del pagamento  |
|  descrizione_prodotto  | Sì | string   |  La descrizione del prodotto  |
|  cliente  | Sì | string   |  L'identificativo di un cliente esistente, oppure `open` per far compilare i dati al cliente sul gateway di pagamento  |
|  data_inizio  | No | string   |  La data di inizio della dilazione in formato `AAAA-MM-GG` (default: oggi)  |
|  tipo  | No | string   |  La tipologia della dilazione, attualmente `credit`  |
|  payment_method  | No | string   |  Il metodo di pagamento: `card` per il pagamento con carta, `sdd` per SEPA Direct Debit  |
|  differenziate  | No | boolean   |  Abilita rate a importi differenti, obbligatorio insieme a `dettaglio_rate`  |
|  dettaglio_rate  | No | int[]   |  L'importo di ogni rata espresso in centesimi, la lunghezza dell'array deve essere uguale al numero di rate, obbligatorio per rate differenziate |
|  consenso_debit  | No | boolean   |  Abilita l'accettazione delle carte di debito e/o prepagate; non obbligatorio, il valore predefinito è `false`  |
|  external_vendor_id  | No | string   |  L'identificativo della pratica nel tuo gestionale  |
|  metadata  | No | object   |  Un oggetto di valori personalizzati restituito nelle risposte e nei webhook  |
|  note  | No | string   |  Delle note descrittive per la dilazione  |

**shell**

 ```bash
 curl "https://api.jatapay.it/scrivi_dilazione" \
  -H "Authorization: Bearer IL_TOKEN_DI_ACCESSO" \
  -H "Content-Type: application/json" \
  -d '{
    "importo": 2000,
    "rate": 2,
    "callback_url": "https://e-commerce.example.com/callback_url",
    "note": "Dilazione per motivo esempio",
    "cliente": "open",
    "descrizione_prodotto": "Descrizione del prodotto"
  }'
```
**PHP**

 ```PHP
 $dati_dilazione = array(
            'importo' => 2000, //Importo in centesimi di euro
            'rate' =>  (int)2 //Numero di rate,
            'callback_url' => 'https://e-commerce.example.com/callback_url',
            'note' => 'Dilazione per motivo esempio',
            'cliente' => 'open',
            'descrizione_prodotto' => 'Descrizione del prodotto'
          );

    $url = curl_init("https://api.jatapay.it/scrivi_dilazione");
    $authorization = "Authorization: Bearer ".$token;
    curl_setopt($url, CURLOPT_CUSTOMREQUEST, "POST");
    curl_setopt($url, CURLOPT_POSTFIELDS, json_encode($dati_dilazione));
    curl_setopt($url, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($url, CURLOPT_HTTPHEADER, array(
      'Content-Type: application/json',
      'Content-Length: ' . strlen(json_encode($dati_dilazione)),
      $authorization
    ));

    $result = curl_exec($url);

    $api_response = json_decode($result);

    curl_close($url);
```

**Python**

```python
import requests
import json

dati_dilazione = {
    'importo': 2000,  # Importo in centesimi di euro
    'rate': 2,  # Numero di rate
    'callback_url': 'https://e-commerce.example.com/callback_url',
    'note': 'Dilazione per motivo esempio',
    'cliente': 'open',
    'descrizione_prodotto': 'Descrizione del prodotto'
}

url = "https://api.jatapay.it/scrivi_dilazione"
token = "your_access_token"  # il tuo token
authorization = "Bearer " + token

headers = {
    'Content-Type': 'application/json',
    'Authorization': authorization
}

response = requests.post(url, data=json.dumps(dati_dilazione), headers=headers)

api_response = response.json()

print(api_response)

```

**Node.js**

```javascript
const token = 'IL_TOKEN_DI_ACCESSO';

const body = {
  importo: 2000, // Importo in centesimi di euro
  rate: 2, // Numero di rate
  callback_url: 'https://e-commerce.example.com/callback_url',
  note: 'Dilazione per motivo esempio',
  cliente: 'open',
  descrizione_prodotto: 'Descrizione del prodotto'
};

const response = await fetch('https://api.jatapay.it/scrivi_dilazione', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});

console.log(response.status, await response.json());
```

**Go**

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	const token = "IL_TOKEN_DI_ACCESSO"

	body := `{
  "importo": 2000,
  "rate": 2,
  "callback_url": "https://e-commerce.example.com/callback_url",
  "note": "Dilazione per motivo esempio",
  "cliente": "open",
  "descrizione_prodotto": "Descrizione del prodotto"
}`

	req, err := http.NewRequest("POST", "https://api.jatapay.it/scrivi_dilazione", strings.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}

	fmt.Println(res.StatusCode, string(data))
}
```

**.NET**

```csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string token = "IL_TOKEN_DI_ACCESSO";

        var body = """
            {
              "importo": 2000,
              "rate": 2,
              "callback_url": "https://e-commerce.example.com/callback_url",
              "note": "Dilazione per motivo esempio",
              "cliente": "open",
              "descrizione_prodotto": "Descrizione del prodotto"
            }
            """;

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

        var content = new StringContent(body, Encoding.UTF8, "application/json");
        var response = await client.PostAsync("https://api.jatapay.it/scrivi_dilazione", content);

        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String token = "IL_TOKEN_DI_ACCESSO";

        String body = """
                {
                  "importo": 2000,
                  "rate": 2,
                  "callback_url": "https://e-commerce.example.com/callback_url",
                  "note": "Dilazione per motivo esempio",
                  "cliente": "open",
                  "descrizione_prodotto": "Descrizione del prodotto"
                }
                """;

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.jatapay.it/scrivi_dilazione"))
                .header("Authorization", "Bearer " + token)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

Il comando ritornerà un JSON con questa struttura:

```json
{
    "app": false,
    "id_dilazione": "6aec4cd9010c3c59f018f590",
    "link_to_pay": false,
    "payment_url": "https://react.jatapay.it/gateway/6aec4cd9010c3c59f018f590"
}
```

### Risposta

| Campo | Tipo |  Descrizione |
| -------------- | -------------- |-------------- |
| app   | boolean |  Indica se la richiesta arriva da un client applicativo interno (flag riservato)   |
| id_dilazione   | string |  L'identificativo della dilazione appena creata   |
| link_to_pay   | boolean |  Indica se la dilazione è stata creata come link di pagamento condivisibile   |
| payment_url   | string |  L'URL a cui reindirizzare l'utente per completare il pagamento   |

:::warning
 La richiesta deve avere l'header Content-Type: application/json e includere il parametro nel corpo del JSON e l'header Authorization: Bearer token
:::

### Reindirizzare l'utente al gateway di pagamento

Una volta creata la dilazione bisogna reindirizzare l'utente all'URL restituito nel campo `payment_url` della risposta:

```bash
https://react.jatapay.it/gateway/ID_DELLA_DILAZIONE
```

L'utente completerà il processo di pagamento e sarà reindirizzato all'url passato in precedenza.

### Gestire il ritorno del pagamento

In qualunque momento sarà possibile recuperare le informazioni sulla dilazione per il controllo dell'avvenuta attivazione della stessa.

```bash
GET https://api.jatapay.it/entity/dilazioni/ID_DELLA_DILAZIONE
```

:::warning
Sostituire ID_DELLA_DILAZIONE con l'id ottenuto in precedenza
:::

Lo stato dilazione 'attiva' indica l'accettazione della dilazione

**shell**

 ```bash
    curl "https://api.jatapay.it/entity/dilazioni/ID_DELLA_DILAZIONE" \
  -H "Authorization: Bearer IL_TOKEN_DI_ACCESSO"
```
**PHP**

 ```PHP
$urlstring = "https://api.jatapay.it/entity/dilazioni/".$_GET['id_dilazione'];
    $url = curl_init($urlstring);
    $authorization = "Authorization: Bearer ".$token;
    curl_setopt($url, CURLOPT_CUSTOMREQUEST, "GET");
    curl_setopt($url, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($url, CURLOPT_HTTPHEADER, array(
      $authorization
    ));

    $result = curl_exec($url);
    curl_close($url);
    $api_response = json_decode($result);
```
**Python**

```python
import requests
import cgi

form = cgi.FieldStorage()

id_dilazione = form.getValue('id_dilazione')
token = 'IL_TUO_TOKEN'
headers = {"Authorization": "Bearer " + token}
url = 'https://api.jatapay.it/entity/dilazioni/' + id_dilazione
response = requests.get(url,headers=headers)
if response.status_code == 200:
  response = response.json()
else:
  print('Error, ' + str(response.status_code))
```

**Node.js**

```javascript
const token = 'IL_TOKEN_DI_ACCESSO';
const idDilazione = 'ID_DELLA_DILAZIONE';

const response = await fetch(`https://api.jatapay.it/entity/dilazioni/${idDilazione}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
console.log(response.status, data);
```

**Go**

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	const token = "IL_TOKEN_DI_ACCESSO"
	idDilazione := "ID_DELLA_DILAZIONE"

	req, err := http.NewRequest("GET", "https://api.jatapay.it/entity/dilazioni/"+idDilazione, nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+token)

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}

	fmt.Println(res.StatusCode, string(data))
}
```

**.NET**

```csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string token = "IL_TOKEN_DI_ACCESSO";
        const string idDilazione = "ID_DELLA_DILAZIONE";

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

        var response = await client.GetAsync($"https://api.jatapay.it/entity/dilazioni/{idDilazione}");

        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String token = "IL_TOKEN_DI_ACCESSO";
        String idDilazione = "ID_DELLA_DILAZIONE";

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.jatapay.it/entity/dilazioni/" + idDilazione))
                .header("Authorization", "Bearer " + token)
                .GET()
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

Il comando ritornerà un JSON con questa struttura:
```json
{
    "_id": "ID_DELLA_DILAZIONE",
    "base": 0, //questo è il valore base della dilazione qualora si usassero rate differenziate
    "callback_url":"https://my-ecommerce.example.com/callback_url", //il callback_url massato in precedenza
    "carta": "6dasde43eww6c4039f27", //l'identificativo della carta del cliente
    "client": "JataPay",
    "cliente": "5f12321was23e3ec1422", //l'identificativo del cliente
    "contratto": {
        "pdf": "6065ef23se35d684823ec387", //l'identificativo del contratto di dilazione
    },
    "data_fine": "Sat, 01 May 2021 18:05:04 GMT", //la data fine della dilazione
    "data_inizio": "Thu, 01 Apr 2021 18:05:04 GMT", //la data inizio della dilazione
    "data_inserimento": "Thu, 01 Apr 2021 16:05:06 GMT", //la data inserimento della dilazione
    "date_differenziate": false,
    "esercente": "6022a3c41bsa3653fsib044", //il vostro identificativo
    "importo": 200, //l'importo in centesimi di euro
    "metadata": null,
    "note": "", //le note inserite
    "numero": 526, //il numero della dilazione
    "rate": 2,
    "rate_differenziate": false, //se la dilazione ha o meno rate differenziate
    "stato": "attiva", //lo stato della dilazione
    "tipo": "credit", //il tipo

}
```

#### Ricevere il webhook

In alternativa al polling puoi ricevere una notifica HTTP `POST` quando lo stato cambia, senza dover interrogare le API.

Il webhook si configura dalla Dashboard nella sezione **[Sviluppatori](https://dashboard.jatapay.it/sviluppatori)** oppure via API con l'endpoint `POST /esercente/developer_options` (vedi [Opzioni sviluppatore](/riferimento-api/opzioni-sviluppatore)).

Ogni notifica è firmata con il `webhook_secret` dell'esercente: vedi [Webhook](/riferimento-api/opzioni-sviluppatore/webhook) per il calcolo e la verifica della firma in tutti i linguaggi.